Co-authored-by: Cursor <cursoragent@cursor.com>

…ssion

Stacks on PR-B3 (#46). When this PR is merged, PR-B3 lands along
with it.

Public API matches the ADR 0008 \u00a73.1 example exactly:

    from kakeya import Client

    with Client('localhost:50051') as client:
        with client.create_session(eos_token_ids=[151645]) as session:
            session.append([10, 20, 30])
            for token_id in session.generate(max_tokens=64):
                print(token_id)

Surface (sdks/python/kakeya/):

  client.py (Client)
    - .address / .closed properties
    - .create_session(eos_token_ids, client_label) -> Session
    - .close() / context manager
    - Wraps grpc.insecure_channel + RuntimeServiceStub (sync)

  session.py (Session, SessionInfo)
    - .session_id / .closed
    - .last_stop_reason / .last_generated_token_count /
      .last_prefill_duration_seconds / .last_total_duration_seconds /
      .last_history_truncated_dropped (populated by .generate)
    - .append(token_ids) -> int
    - .generate(max_tokens, seed, temperature, top_p, top_k) -> Iterator[int]
    - .info() -> SessionInfo
    - .close() / context manager
    - SessionClosedError on local-side reuse after close()

  errors.py (typed exception hierarchy)
    - KakeyaError (base, carries .rpc_code)
    - SessionNotFoundError       <- gRPC NOT_FOUND
    - InvalidArgumentError       <- gRPC INVALID_ARGUMENT
    - InvariantViolationError    <- gRPC FAILED_PRECONDITION
    - ResourceExhaustedError     <- gRPC RESOURCE_EXHAUSTED
    - UnimplementedError         <- gRPC UNIMPLEMENTED
    - RpcCancelledError          <- gRPC CANCELLED
    - SessionClosedError         <- client-side, never crosses the wire

Sync vs async: PR-B4 ships sync only (grpc.insecure_channel). The
ADR \u00a73.1 example is sync, and the v0.3 target audience (REPL,
scripts, agent harnesses on a single Mac) prefers sync. An async
API can be added in a later PR without breaking this surface; the
runtime is identical (grpc.aio.server is wire-compatible with sync
clients).

Tokenization: per ADR \u00a72.4 / \u00a73.4, the SDK ships ZERO chat-template
logic. The runtime treats token ids as opaque integers; rendering
messages to tokens lives in sdks/python/examples/ (a future PR).

Tests (tests/sdk/python/):

  test_errors.py       (20 tests)
    Every gRPC StatusCode -> typed-exception mapping verified.
    Plus the catch-all path for unknown codes, the .rpc_code carry,
    and the SessionClosedError no-rpc-code variant.

  test_client.py       (13 tests)
    Construction, address property, closed flag, idempotent close,
    context manager, create_session with all argument combinations,
    RESOURCE_EXHAUSTED -> ResourceExhaustedError end-to-end.

  test_session.py      (33 tests)
    All 5 RPC methods, all error mappings, last_* metadata fields,
    HistoryTruncated -> .last_history_truncated_dropped, sampling
    param validation (greedy-only contract surfaces as
    InvalidArgumentError), context manager, double-close idempotency,
    SessionInfo dataclass standalone construction + repr.

All 66 tests run against a real grpc.aio runtime spun up in a
background thread (see tests/sdk/python/conftest.py). The
fixture creates the gRPC server INSIDE the worker thread's loop
(not the main thread) to avoid 'Future attached to a different
loop' from grpcio's internals; shutdown uses
server.wait_for_termination() so the loop can exit cleanly without
a cancellation tantrum.

CI changes (.github/workflows/ci.yaml):
  - PYTHONPATH gains sdks/python so 'import kakeya' resolves
    without pip-install (consistent with the rest of the repo's
    PYTHONPATH-based layout).
  - tests/sdk/python/ added to pytest paths.
  - --cov=kakeya added to the coverage gate.
  - package-import-smoke imports kakeya, kakeya.client,
    kakeya.session, kakeya.errors (regression catches an
    accidentally-broken __init__).

Mac M4 reviewer aid (\u00a79 carve-out applies — Linux-only path):
  scripts/review_pr_b4_on_mac.sh
    Runs SDK pytest + 100% coverage gate, plus all three prior
    PR-B1/B2/B3 smokes for regression. Produces 4 JSON artifacts
    under results/platform-tests/.

Local verification (Linux VM, py3.12):
  Linux CI gate: 695 passed (was 629 + 66 new). Coverage 100.00%
                 on 1694 stmts (was 1521 + 173 new = sdk surface).
  Reviewer script end-to-end:
    SDK tests       : 66 tests, cov=173/173=100%
    Runtime smoke   : 10/10
    Appender smoke  : 10/10
    Generator smoke : 10/10

Next PR after merge:
  PR-B5 (\u00a76.2): TypeScript SDK under sdks/typescript/. Targets
        Node.js 20+ / Electron 30+ / Bun 1.1+. Generates stubs
        from proto/kakeya/v1/runtime.proto via protoc-gen-ts_proto.
        Linux-only path; \u00a79 carve-out continues to apply.

Co-authored-by: FluffyAIcode <FluffyAIcode@users.noreply.github.com>

Final PR of Phase B. Stacks on PR-B4 (#47); when this merges,
PR-B4 lands along with it.

Public API matches the ADR 0008 \u00a73.2 example exactly and mirrors
the Python SDK at sdks/python/kakeya/* symbol-for-symbol (modulo
TypeScript naming convention: PascalCase classes, camelCase
fields). Cross-language symmetry makes the wire contract auditable
by simple grep.

  import { Client } from '@kakeya/runtime';

  const client = new Client('localhost:50051');
  try {
    const session = await client.createSession({ eosTokenIds: [151645] });
    try {
      await session.append([10, 20, 30]);
      for await (const tokenId of session.generate({ maxTokens: 64 })) {
        console.log(tokenId);
      }
    } finally {
      await session.close();
    }
  } finally {
    client.close();
  }

Targets per ADR \u00a73.2:
  Node.js >= 20.0.0 (engines.node enforced in package.json)
  Electron 30+ and Bun 1.1+ are API-compatible (not separately
  CI-tested in v0.3 to keep the matrix small; documented support).
  Browser intentionally NOT supported (gRPC-Web / WebSocket are
  out of scope for v0.3 \u2014 see ADR 0008 \u00a78 OQ-1).

Surface (sdks/typescript/src/):

  index.ts (public exports)
  client.ts (Client + DEFAULT_ADDRESS + ClientOptions)
  session.ts (Session + SessionInfo + GenerateOptions + GenerateResult)
  errors.ts (KakeyaError base + 7 typed subclasses + wrapGrpcError)
  proto_gen/kakeya/v1/runtime.ts (generated, not hand-edited)

Wire transport: @grpc/grpc-js (Node-native HTTP/2). Generated
stubs come from protoc-gen-ts_proto with options:
  esModuleInterop=true,forceLong=string,outputServices=grpc-js,
  useOptionals=messages,stringEnums=false,removeEnumPrefix=true

forceLong=string is the safest choice for uint64 fields (history
lengths, kv_live_bytes, dropped_token_count, seed): JS Number
can't safely represent the full uint64 range, so values cross
the wire as decimal strings and the SDK converts to Number /
keeps as string at the public API boundary.

Error mapping (mirrors Python exactly):
  gRPC NOT_FOUND            -> SessionNotFoundError
  gRPC INVALID_ARGUMENT     -> InvalidArgumentError
  gRPC FAILED_PRECONDITION  -> InvariantViolationError
  gRPC RESOURCE_EXHAUSTED   -> ResourceExhaustedError
  gRPC UNIMPLEMENTED        -> UnimplementedError
  gRPC CANCELLED            -> RpcCancelledError
  (other status)            -> KakeyaError (base, with .rpcCode)
  (client-side)             -> SessionClosedError

Tests (sdks/typescript/test/, 54 vitest cases):

  client.test.ts (14 tests) \u2014 construction, properties,
    idempotent close, all createSession argument paths,
    RESOURCE_EXHAUSTED + NOT_FOUND end-to-end via real gRPC.

  session.test.ts (20 tests) \u2014 all 5 RPC methods, async
    iterator semantics for generate(), HistoryTruncated capture,
    sampling-param wire forwarding, error mappings (NOT_FOUND,
    INVALID_ARGUMENT, FAILED_PRECONDITION), local-close vs
    runtime-eviction split, lastResult reset between calls.

  errors.test.ts (20 tests) \u2014 every gRPC StatusCode -> typed
    subclass, unknown-status fallback, message fallback chain
    (details ?? message ?? '').

  test/server_fixture.ts \u2014 in-Node @grpc/grpc-js test server with
    parameterized canned-response handlers. Real wire format,
    real gRPC stream, real channel \u2014 no mocks of the SUT.

Tooling:

  package.json \u2014 npm package metadata; type=module; engines.node>=20.
  tsconfig.json \u2014 strict mode, ES2022 target, NodeNext modules.
  vitest.config.ts \u2014 100% coverage thresholds (lines, branches,
    functions, statements all enforced); proto_gen excluded since
    those are protoc's artifact, not our surface (mirrors the
    Python .coveragerc omit pattern).

  scripts/regenerate_proto_stubs.sh \u2014 extended to also produce
    TypeScript stubs via grpc_tools.protoc + protoc-gen-ts_proto.
    Single canonical regen command for all SDKs.

  .github/workflows/ci.yaml:
    - proto-stub-drift job extended: now also drift-checks TS
      stubs (regenerates and git-diff-exit-codes). Adds Node 20
      + ts-proto install before the regen step.
    - typescript-sdk-tests new job: setup-node@v4 (Node 20),
      npm install in sdks/typescript/, typecheck, vitest with
      100% coverage gate.

Local verification (Linux dev VM):
  npm test:        54 passed, 100% on lines/branches/functions/statements
  npm typecheck:   clean
  Python gate:     695 passed (unchanged, PR-B5 is TS-only)
  Regen idempotent: scripts/regenerate_proto_stubs.sh produces
                    byte-identical Python + TS stubs to committed.

Per ADR 0008 \u00a79: Linux-only path \u2014 zero MLX runtime code; SDK is
pure TypeScript over @grpc/grpc-js. \u00a79 carve-out applies.

Phase B is complete after this PR merges:
  PR-A1 (#40)  proto/runtime.proto + buf
  PR-A2 (#41)  SessionStore + INV-1/2
  PR-A3 (#42)  remove ADR 0007 dead code
  PR-A3b(#43)  session-slab ownership + CacheInspector
  PR-B1 (#44)  gRPC Create/Close/GetSessionInfo
  PR-B2 (#45)  AppendTokens + byte-exact prefill-incremental
  PR-B3 (#46)  Generate server-streaming + greedy decoding
  PR-B4 (#47)  Python SDK (kakeya.Client + Session)
  PR-B5 (this) TypeScript SDK (@kakeya/runtime)

Phase C and beyond: deprecated HTTP shim refactor (PR-D1),
integration test suite (PR-E1), v0.4 multi-tenant + speculative
decoding integration are downstream concerns.

Co-authored-by: FluffyAIcode <FluffyAIcode@users.noreply.github.com>